.TH std::basic_string::capacity 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_string::capacity \- std::basic_string::capacity

.SH Synopsis
   size_type capacity() const;  (noexcept since C++11)
                                (constexpr since C++20)

   Returns the number of characters that the string has currently allocated space for.

.SH Parameters

   \fI(none)\fP

.SH Return value

   Capacity of the currently allocated storage, i.e. the storage available for storing
   elements.

.SH Complexity

   Constant.

.SH Notes

   Memory locations obtained from the allocator but not available for storing any
   element are not counted in the allocated storage. Note that the null terminator is
   not an element of the std::basic_string.

.SH Example


// Run this code

 #include <iomanip>
 #include <iostream>
 #include <string>

 void show_capacity(std::string const& s)
 {
     std::cout << std::quoted(s) << " has capacity " << s.capacity() << ".\\n";
 }

 int main()
 {
     std::string s{"Exemplar"};
     show_capacity(s);

     s += " is an example string.";
     show_capacity(s);

     s.clear();
     show_capacity(s);

     std::cout << "\\nDemonstrate the capacity's growth policy."
                  "\\nSize:  Capacity:  Ratio:\\n" << std::left;

     std::string g;
     auto old_cap{g.capacity()};

     for (int mark{}; mark != 5; ++mark)
     {
         while (old_cap == g.capacity())
             g.push_back('.');

         std::cout << std::setw( 7) << g.size()
                   << std::setw(11) << g.capacity()
                   << std::setw(10) << g.capacity() / static_cast<float>(old_cap) << '\\n';

         old_cap = g.capacity();
     }
 }

.SH Possible output:

 "Exemplar" has capacity 15.
 "Exemplar is an example string." has capacity 30.
 "" has capacity 30.

 Demonstrate the capacity's growth policy.
 Size:  Capacity:  Ratio:
 16     30         2
 31     60         2
 61     120        2
 121    240        2
 241    480        2

.SH See also

   size    returns the number of characters
   length  \fI(public member function)\fP
   reserve reserves storage
           \fI(public member function)\fP
